home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 14 / CU Amiga Magazine's Super CD-ROM 14 (1997)(EMAP Images)(GB)(Track 1 of 3)[!][issue 1997-09].iso / CUCD / Programming / Mesa-2.2 / src-tk / README < prev    next >
Encoding:
Text File  |  1997-01-29  |  10.4 KB  |  338 lines
  1. /*
  2. ** Nano Window Toolkit.
  3. ** Version 1.1
  4. */
  5.  
  6.  
  7. /**********************************************************************/
  8. /*    These functions are new in libtk 1.1                            */
  9. /**********************************************************************/
  10.  
  11. void tkInitDisplayModePolicy( GLenum type)
  12.  
  13.     - Sets the policy to: TK_EXACT_MATCH, TK_MINIMUM_CRITERIA or TK_USE_ID. 
  14.  
  15.        The default policy, TK_MINIMUM_CRITERIA, is the way libtk 1.0 works: 
  16.     it creates a window with capabilities greater than or equal to those 
  17.     specified by the current display mode (See tkInitDisplayMode()). If 
  18.     TK_EXACT_MATCH is chosen, then a window that exactly matches the specified 
  19.     display mode will be selected if possible. (If an exact match cannot be 
  20.     found then tkInitWindow() will return GL_FALSE.) If TK_USE_ID is chosen 
  21.     then the display mode i.d. is used to create the window.
  22.  
  23.  
  24. GLenum tkGetDisplayModePolicy( void)
  25.    
  26.     - Returns the current display mode policy.
  27.  
  28.  
  29. GLenum tkInitDisplayModeID( GLint id)
  30.  
  31.     - Sets the display mode i.d.
  32.  
  33.        The display mode i.d. is used when creating a window, when 
  34.     the policy is TK_USE_ID. (For X and OS2 this is a visual i.d.; 
  35.     for Windows NT this is a pixel format.) Note that display mode
  36.     i.d.'s are machine dependent.
  37.  
  38.  
  39. GLint tkGetDisplayModeID( void)
  40.  
  41.     - Returns the display mode i.d. of the main window.
  42.  
  43.  
  44. GLenum tkGetDisplayMode( void)
  45.  
  46.     - Returns the display mode of the window. 
  47.  
  48.        Window attributes such as TK_RGB and TK_INDIRECT are or'ed 
  49.     together into a single mask and returned.
  50.  
  51.  
  52. Also, tkGetSystem() was extended (complete description is below) to also
  53. return the X screen and the rendering context.
  54.  
  55.  
  56. /**********************************************************************/
  57. /*        The following functions were also part of libtk 1.0         */
  58. /**********************************************************************/
  59.  
  60.  
  61. /*
  62. ** Windowing functions.
  63. */
  64.  
  65. void tkInitDisplayMode(GLenum type);
  66.     - Preset window type.
  67.     - GLenum type:
  68.     TK_RGB or TK_INDEX
  69.     TK_SINGLE or TK_DOUBLE
  70.     TK_DIRECT or TK_INDIRECT
  71.     TK_ACCUM
  72.     TK_ALPHA
  73.     TK_DEPTH
  74.     TK_OVERLAY
  75.     TK_UNDERLAY
  76.     TK_STENCIL
  77.     
  78. void tkInitPosition(int x, int y, int w, int h);
  79.     - Preset window size and top-left corner location.
  80.  
  81. GLenum tkInitWindow(char *titleStr);
  82.     - Create new window.
  83.  
  84.     Use tkInitDisplay to set values determining whether the window 
  85.     requested will be RGB or COLOR_INDEX and what buffer structure you want 
  86.     the window to have.  
  87.         You may request buffers and modes for the window by or'ing the values 
  88.     listed below into the 'type'.  tkInitPosition will similarly set 
  89.     the position and size of the window.  
  90.         The properties set by these functions will be used by 
  91.     tkInitWindow when the window is created. If the window cannot be created 
  92.     with the requested buffers, tkInitWindow prints an diagnostic message and 
  93.     exits.
  94.  
  95. void tkCloseWindow(void);
  96.     - Close window.
  97.  
  98. void tkQuit(void);
  99.     - Quit application.
  100.  
  101.     tkClose window frees the memory used by some of the tk routines,
  102.     calls glFinish, sets the event functions to null, and gets rid of the 
  103.     window.  tkQuit calls tkCloseWindow and exits the current program.
  104.  
  105. GLenum tkSetWindowLevel(GLenum level);
  106.     - Set drawing plane of window.
  107.     - GLenum level:
  108.     TK_RGB or TK_INDEX
  109.     TK_OVERLAY
  110.     TK_UNDERLAY
  111.  
  112.  
  113.     If the window was created with an overlay plane this redirects the
  114.     rendering to the appropriate plane.  TK_UNDERLAY is currently
  115.     not used.  
  116.  
  117.  
  118.  
  119. void tkSwapBuffers(void);
  120.     - Swap draw/view buffer in double buffered window.
  121.  
  122.     If the window supports double-buffering this makes the contents
  123.     of the back buffer visible, performing an implicit glFlush().
  124.     The contents of the back buffer are undefined after this call.
  125.  
  126.  
  127.  
  128. /*
  129. ** Event functions.
  130. */
  131.  
  132.     The user may want to create an Expose, a Reshape, and a Display 
  133.     callback function for use by the tk event structure. Some of these 
  134.     events may correspond to window system events, and others are input
  135.     events. The event loop code can be better understood by looking
  136.     at the tkExec function in the file 'event.c'. The functions below
  137.     are used to set the various callback functions.
  138.  
  139. void tkExposeFunc(void (*Func)(int w, int h));
  140.     - Set window expose callback routine.
  141.     - void (*Func)(int w, int h)
  142.     - Callback routine will receive window size at window expose time.
  143.  
  144. void tkReshapeFunc(void (*Func)(int w, int h));
  145.     - Set window reshape callback routine.
  146.     - void (*Func)(int w, int h)
  147.     - Callback routine will receive window size after window reshape.
  148.  
  149. void tkDisplayFunc(void (*Func)(void));
  150.     - Set display callback routine.
  151.     - In general this should do *most* of the drawing. It should draw the
  152.     entire screen.
  153.  
  154. void tkKeyDownFunc(GLenum (*Func)(int key, GLenum states));
  155.     - Set key event callback routine.
  156.     - void (*Func)(int key, GLenum states)
  157.     - Callback routine will receive key pressed and state of the
  158.       shift and control keys.
  159.     - Callback routine will return GL_TRUE if the display callback
  160.       routine should be called or GL_FALSE if the display callback
  161.       should not be called.
  162.     - int key:
  163.         TK_ESCAPE
  164.         TK_LEFT TK_UP TK_RIGHT TK_DOWN
  165.         TK_RETURN
  166.         TK_SPACE
  167.         TK_A through TK_Z
  168.         TK_a through TK_z
  169.         TK_0 through TK_9
  170.     - GLenum states:
  171.         TK_SHIFT
  172.         TK_CONTROL
  173.  
  174. void tkMouseDownFunc(GLenum (*Func)(int x, int y, GLenum states));
  175.     - Set mouse button down event callback routine.
  176.     - void (*Func)(int x, int y, GLenum states)
  177.     - Callback routine will receive mouse x, y location and button states
  178.       when the mouse button down event occurred.
  179.     - Callback routine will return GL_TRUE if the display callback
  180.       routine should be called or GL_FALSE if the display callback
  181.       should not be called.
  182.     - GLenum states:
  183.         TK_LEFTBUTTON
  184.         TK_RIGHTBUTTON
  185.         TK_MIDDLEBUTTON
  186.  
  187. void tkMouseUpFunc(GLenum (*Func)(int x, int y, GLenum states));
  188.     - Set mouse button up event callback routine.
  189.     - void (*Func)(int x, int y, GLenum states)
  190.     - Callback routine will receive mouse x, y location and button states
  191.       when the mouse button up event occurred.
  192.     - Callback routine will return GL_TRUE if the display callback
  193.       routine should be called or GL_FALSE if the display callback
  194.       should not be called.
  195.     - GLenum states:
  196.         TK_LEFTBUTTON
  197.         TK_RIGHTBUTTON
  198.         TK_MIDDLEBUTTON
  199.  
  200. void tkMouseMoveFunc(GLenum (*Func)(int x, int y, GLenum states));
  201.     - Set mouse move event callback routine.
  202.     - void (*Func)(int x, int y, GLenum states)
  203.     - Callback routine will receive mouse x, y location and button states
  204.       when the mouse move event occurred.
  205.     - Callback routine will return GL_TRUE if the display callback
  206.       routine should be called or GL_FALSE if the display callback
  207.       should not be called.
  208.     - GLenum states:
  209.         TK_LEFTBUTTON
  210.         TK_RIGHTBUTTON
  211.         TK_MIDDLEBUTTON
  212.  
  213. void tkIdleFunc(void (*Func)(void));
  214.     - Set idle event callback routine.
  215.     - Idle is for when the there are no events.
  216.  
  217.  
  218. void tkExec(void)
  219.     - Pass control to tk's event handling code. See file event.c for
  220.       exact flow control algorithm.
  221.  
  222. /*
  223. ** Get functions.
  224. */
  225.  
  226.  
  227. int tkGetColorMapSize(void);
  228.     - return size of color map.
  229.  
  230. void tkGetMouseLoc(int *x, int *y);
  231.     - return current mouse x, y location.
  232.  
  233. void tkGetSystem(GLenum type, void *ptr)
  234.     - returns either the X display, X window, X screen or rendering context depending 
  235.       on type (note: the X display, X window and X screen are only supported on versions
  236.       of the library that run under X windows)
  237.  
  238. /*
  239. ** Set functions.
  240. */
  241.     These functions set color maps for use by the windowing system.
  242.  
  243. void tkSetOneColor(int ci, float r, float g, float b);
  244.     - Set color index to the r, g, b values.
  245.  
  246. void tkSetFogRamp(int density, int size);
  247.     - Set up a fog ramp in the color map starting at entry 0 and of length
  248.       2^size.
  249.  
  250. void tkSetGreyRamp(void);
  251.     - Set the entire color map to a grey scale ramp.
  252.  
  253. void tkSetRGBMap(int size, float *rgb);
  254.     - Set up the main window's color map. The rgb values are in the form
  255.       r[size] followed by g[size] followed by b[size].
  256.  
  257. void tkSetOverlayMap(int, float *);
  258.     - Set up the overlay plane's color map. The rgb values are in the form
  259.       r[size] followed by g[size] followed by b[size].
  260.  
  261. /*
  262. ** Cursor functions.
  263. */
  264.  
  265. void tkNewCursor(GLint id, GLubyte *shape, GLubyte *mask, GLenum fgColor,
  266.          GLenum bgColor, GLint hotX, GLint hotY)
  267.     - Define and initialize a cursor.
  268.     - GLenum fgColor, bgColor:
  269.     TK_BLACK
  270.     TK_RED
  271.     TK_GREEN
  272.     TK_YELLOW
  273.     TK_BLUE
  274.     TK_MAGENTA
  275.     TK_CYAN
  276.     TK_WHITE
  277.  
  278. void tkSetCursor(GLint id);
  279.     - Make cursor active.
  280.  
  281. /*
  282. ** Simple object function.
  283. */
  284.  
  285. void tkWireSphere(GLuint base, float radius);
  286. void tkSolidSphere(GLuint base, float radius);
  287. void tkWireCube(GLuint base, float size);
  288. void tkSolidCube(GLuint base, float size);
  289. void tkWireBox(GLuint base, float width, float height, float depth);
  290. void tkSolidBox(GLuint base, float width, float height, float depth);
  291. void tkWireTorus(GLuint base, float innerRadius, float outerRadius);
  292. void tkSolidTorus(GLuint base, float innerRadius, float outerRadius);
  293. void tkWireCylinder(GLuint base, float radius, float height);
  294. void tkSolidCylinder(GLuint base, float radius, float height);
  295. void tkWireCone(GLuint base, float b, float h);
  296. void tkSolidCone(GLuint base, float b, float h);
  297.     - Creates various display list shapes starting at the given base.
  298.  
  299. /* 
  300. ** Helpful window mask tests.
  301. */
  302.  
  303. #define TK_IS_RGB(x)        (((x) & TK_INDEX) == 0)
  304. #define TK_IS_INDEX(x)        (((x) & TK_INDEX) != 0)
  305. #define TK_IS_SINGLE(x)        (((x) & TK_DOUBLE) == 0)
  306. #define TK_IS_DOUBLE(x)        (((x) & TK_DOUBLE) != 0)
  307. #define TK_IS_DIRECT(x)        (((x) & TK_INDIRECT) == 0)
  308. #define TK_IS_INDIRECT(x)    (((x) & TK_INDIRECT) != 0)
  309. #define TK_HAS_ACCUM(x)        (((x) & TK_ACCUM) != 0)
  310. #define TK_HAS_ALPHA(x)        (((x) & TK_ALPHA) != 0)
  311. #define TK_HAS_DEPTH(x)        (((x) & TK_DEPTH) != 0)
  312. #define TK_HAS_OVERLAY(x)    (((x) & TK_OVERLAY) != 0)
  313. #define TK_HAS_UNDERLAY(x)    (((x) & TK_UNDERLAY) != 0)
  314. #define TK_HAS_STENCIL(x)    (((x) & TK_STENCIL) != 0)
  315.  
  316. /*
  317. ** Helpful color macro.
  318. */
  319.  
  320. #define TK_SETCOLOR(windType, color) (TK_IS_RGB((windType)) ? \
  321.                      glColor3fv(tkRGBMap[(color)]) : \
  322.                      glIndexf((color)))
  323.     - GLenum windType:
  324.     TK_RGB or TK_INDEX
  325.     - GLenum color:
  326.     TK_BLACK
  327.     TK_RED
  328.     TK_GREEN
  329.     TK_YELLOW
  330.     TK_BLUE
  331.     TK_MAGENTA
  332.     TK_CYAN
  333.     TK_WHITE
  334.  
  335. known bugs: The x implementations of this does not set some of the 
  336. x-properties.  There is a lot of potential for name-space collisions.  
  337. (This library uses the terms 'xDisplay', 'xScreen', and 'w' to name a few.
  338.